package com.kktoolbox.model;

/**
 * 搜索进度回调接口
 * 
 * <p>该接口定义了PDF搜索过程中的进度回调方法，
 * 允许搜索引擎向UI组件报告搜索进度和状态更新。</p>
 * 
 * <p>通过实现此接口，UI组件可以：</p>
 * <ul>
 *   <li>实时显示搜索进度</li>
 *   <li>更新进度条和状态信息</li>
 *   <li>处理搜索完成事件</li>
 *   <li>提供用户友好的反馈</li>
 * </ul>
 * 
 * <p>该接口采用观察者模式，搜索引擎作为被观察者，
 * UI组件作为观察者，实现松耦合进度通知机制。</p>
 * 
 * <p>使用示例：</p>
 * <pre>{@code
 * SearchProgressCallback callback = new SearchProgressCallback() {
 *     @Override
 *     public void onProgressUpdate(int current, int total) {
 *         progressBar.setValue((int)((current * 100.0) / total));
 *         statusLabel.setText("正在搜索: " + current + "/" + total);
 *     }
 *     
 *     @Override
 *     public void onStatusUpdate(String status) {
 *         statusLabel.setText(status);
 *     }
 *     
 *     @Override
 *     public void onSearchComplete() {
 *         statusLabel.setText("搜索完成");
 *         progressBar.setValue(100);
 *     }
 * };
 * 
 * PDFSearchEngine engine = new PDFSearchEngine();
 * engine.searchPDFs(directory, keyword, callback);
 * }</pre>
 * 
 * @author KK-Toolbox
 * @version 1.0.0
 * @since 2025-01-01
 * @see PDFSearchEngine
 */
public interface SearchProgressCallback {
    
    /**
     * 进度更新回调方法
     * 
     * <p>当搜索引擎处理文件时调用此方法，报告当前进度。
     * 通常用于更新进度条和显示处理状态。</p>
     * 
     * <p>该方法在搜索线程中被调用，如果需要更新UI组件，
     * 请确保在EDT（Event Dispatch Thread）中执行UI更新操作。</p>
     * 
     * <p>进度计算示例：</p>
     * <pre>{@code
     * int percentage = (int)((current * 100.0) / total);
     * progressBar.setValue(percentage);
     * }</pre>
     * 
     * @param current 当前已处理的文件数量，从1开始计数
     * @param total   总文件数量，总是大于0
     * 
     * @implNote 实现者应确保此方法执行快速，避免阻塞搜索线程
     * @implNote 如果total为0，current也应为0，表示没有文件需要处理
     */
    void onProgressUpdate(int current, int total);
    
    /**
     * 状态更新回调方法
     * 
     * <p>当搜索引擎需要报告状态信息时调用此方法。
     * 状态信息通常包括当前正在处理的文件名、
     * 搜索阶段描述或其他用户友好的信息。</p>
     * 
     * <p>常见的状态信息包括：</p>
     * <ul>
     *   <li>"正在扫描目录..."</li>
     *   <li>"正在搜索: filename.pdf"</li>
     *   <li>"正在统计PDF文件..."</li>
     *   <li>"搜索已取消"</li>
     *   <li>"发生错误: 错误描述"</li>
     * </ul>
     * 
     * @param status 状态描述字符串，不会为null，但可能为空字符串
     * 
     * @implNote 实现者应将此信息显示给用户，通常在状态栏或标签中
     * @implNote 该方法在搜索线程中被调用，UI更新需要切换到EDT
     */
    void onStatusUpdate(String status);
    
    /**
     * 搜索完成回调方法
     * 
     * <p>当搜索过程完全结束时调用此方法，
     * 无论搜索是正常完成、被用户取消还是发生错误。</p>
     * 
     * <p>此方法被调用后，搜索引擎不会再调用其他回调方法。
     * 实现者可以在此方法中执行清理工作和最终的UI更新。</p>
     * 
     * <p>典型的完成处理包括：</p>
     * <ul>
     *   <li>隐藏或重置进度条</li>
     *   <li>更新状态信息为"搜索完成"</li>
     *   <li>重新启用搜索按钮</li>
     *   <li>显示搜索结果统计</li>
     *   <li>执行必要的资源清理</li>
     * </ul>
     * 
     * @implNote 该方法在搜索线程中被调用，UI更新需要切换到EDT
     * @implNote 实现者应确保此方法不抛出异常，以免影响搜索引擎的清理工作
     */
    void onSearchComplete();
}